Model Property Editor
This document describes how to use the model property editor, a separate application that allows you to edit ships. It's located in the Tools subdirectory. Before you run the application, it is recommended that you run the included registry file (modelpropertyeditor.reg). This will enter some of the preferences needed to work with Bridge Commander into the registry.
Setting up the editor
When you run the editor, the first thing you'll want to do is set up your preferences. Select Edit -> Options... to open up the Options dialog box. If you ran the included registry file, the model scale and texture path should already be set up. Change the default model directory to wherever you have Bridge Commander installed, in the 'data\models\ships' subdirectory. Then, change the default script directory to point to the 'scripts\ships\hardpoints' subdirectory where BC is installed. Warning: you should only have one file open at once in the editor.
Using the editor
Select Open from the File menu. You'll be presented with the models directory, from which you should choose a model. You'll then be asked if you want to load a script -- if you're modifying a ship, say yes, and then select its script from the dialog box. If you're starting from scratch, hit no, and you'll be left with a blank slate.
On the right hand side of the window, you'll see a tree representing the scene graph of the model. Open up the tree until you reach 'Scene Root', and select that. (The editor supports placing properties at any location in the model, but Bridge Commander expects them to all be at 'Scene Root'.) If you loaded a script, you'll probably see a list of properties fill up the left hand side of the screen. These are the properties that are actually attached to the model.
Moving around the editor
The center view can be used to examine the model. You can use the mouse to move around the view window in various ways. Normally, the mouse is in a certain "click mode", indicated in the bottom right corner of the tool bar. For example, in "pan mode", dragging with the left mouse button in the view will pan the camera around. These modes are accessible from the View menu.
Alternately, you can use the middle and right mouse buttons, along with the mouse wheel, to move directly. Right-dragging in the view will rotate the camera. Dragging with the middle button will pan the camera, and rolling up and down with the mouse wheel will move the camera forward and backward.
Here is a brief summary of what each mode in the editor does:
- Pan tool will allow you to pan the camera when dragging in the view.
- Orbit tool will swing the camera around a point in front of it.
- Zoom tool will move the camera forward and backwards.
- Selection tool will pick the model leaf that you click on in the scene graph representation. Not really useful for editing ships, this is here as more of an aid to checking models.
- Locate tool will store the coordinates of the point you click on, in the bottom part of the toolbar. This is useful for editing systems, so you can specify where they are attached easily. This also stores the normal of the point.
- Rotate tool will rotate the camera when you drag in the view.
Creating and editing properties
In Bridge Commander, properties usually describe systems attached to the ship. All of the properties in the script are listed in the template list, which can be accessed under the Properties menu. This dialog will allow you to create new properties, edit existing ones, and move ones between the global and local lists (advanced usage -- not really necessary for editing ships). It is recommended that you use the local lists only, located on the right hand side of the dialog.
Selecting New... will let you create a new property, by choosing from some predefined types. Select the one that you want, and a name for it, and it will be added to the set you chose. You can then edit it, if you choose, by double-clicking it or selecting Edit. This will bring up a dialog box whose contents will depend on what type of property you selected.
When you are done editing the property, you still need to add it to the model for it to be recognized by the game. Close the template list, and select 'Scene Root' out of the scene graph on the right-hand-side of the main window. Then, click Add Property, on the left hand side of the window. You can then select the property to add. It will be attached to the model.
Using hardpoint scripts with Bridge Commander
When you save your hardpoint script, it should be in the "scripts/ships/Hardpoints" directory under Bridge Commander. In order to use it, you'll need a corresponding "ship script" that points to the hardpoint script. These files are located in the "scripts/ships" directory.
If you've just modified an existing ship (and didn't overwrite its hardpoint file), it's easiest to just make a copy of that ship's ship script, rename it to your new ship's name, then edit it to point to the correct hardpoint script. Copy the ship script (in "scripts/ships"), rename it, then change the "HardpointFile" entry at the top of the file to the name of your new hardpoint script (minus the .py extension).
Now, if a mission creates your ship using loadspacehelper.CreateShip(), it will use the right hardpoint file and you'll have your modified ship in the game.
Reference for specific properties
Each of the properties you can add to a model has a specific purpose. Some of them can be very complex, and inherit features from other properties, while others are fairly simple. This section will start with the properties that are basic building blocks of others, and move on to more specialized ones.
Note: The names of these properties usually correspond with the tabs that appear in the property editing dialogs.
-
Subsystem Property: This cannot be created explicitly, but is part of almost all other properties. When selected, the subsystem is usually represented in the 3D view as a 3-dimensional crosshair.
- Hit points. This is the amount of damage the system can take before being destroyed.
- Repair complexity. This is a multiplier specifying how difficult it is to repair the system. 1.0 is normal, lower numbers will make the system repair faster, higher numbers will make it slower.
- Disabled at (%). This specifies the percentage of hit points at which the system will be disabled. For some subsystems, this does nothing.
- Radius. This specifies the radius of the sphere that this system occupies. Weapons fire that hits anywhere in this radius will damage this system.
- Flags. Critical specifies whether destroying this system will destroy the ship. Targetable determines whether the system can be damaged, and targeted. Primary is used if you have multiple systems of the same type (only really usable for hulls), and marks which one is considered the main system.
- 3D Position. This is the 3D position on the model that this system occupies. You can enter it either numerically, or by using the Locate mode of the viewer to choose a point, then clicking the Get Position button. Clicking and dragging on the Slide button with the left mouse button will move it along two axes, and dragging with the right mouse button will move it along the third. Holding down the Shift or Ctrl key will constrain the movement to a particular axis.
- 2D Overlay Position. This indicates the location, in pixels, of the icon representing the system on the 2D damage display.
-
Position/Orientation Property: This is a position/orientation pair used on a model. This, or similar editing controls, are used in a couple of places, such as weapons. These are usually represented in the 3D view as a set of axes, with the red line being forward, green being up, and blue being right.
- Direction, Up, Right. These are the three unit vectors that define the orientation, or which way the thing is pointing. It's probably easiest to edit this using the Spin drag control, which works similarly to the Slide button mentioned above -- click and drag with either the left or right mouse button. Clicking the Normal button will fill in this information with the normal set using Locate mode in the editor.
- 3D Position. Same as above.
-
Emitter properties.: These are basically identical to Position/Orientation properties, and are currently only used for the bridge models.
-
Ship Property: This is used to hold some general information about a ship.
- Ship genus: Used to specify whether a ship belongs to the "ship", "station", or "asteroid" groups. Look for "GENUS_" in scripts/App.py for the values, or just copy them from other ships.
- Ship species: Used to specify the species type of a ship. Used to determine which icon to show in the target displays, for example. Again, look in scripts/App.py for "SPECIES_" for some values. Anything not defined is fair game, but be careful not to cause conflicts between two ships.
- Mass: how massive the ship is. Affects collisions.
- Rotational inertia: Affects the ship's ability to stop turning.
- Stationary: Set this for objects that will never move.
- Ship name, Model file name, Damage resolution, Affiliation: Unused. Most of these are specified in the "ship file", not the hardpoint file.
- AI String: specifies the script to use for the default attack AI. i.e. FedAttack, NonFedAttack, StarbaseAttack.
- Death explosion sound: specifies the sound name (not the file name) to use for death explosions.
- Powered Subsystem: like Subsystem Properties, cannot be created directly, but is used by many other things.
- Normal power/second: how much power is drained by this system per second, at 100% power.
- Cloaking Subsystem: Adding this will add a cloaking system to the ship.
- Cloak strength: not used.
- Sensor Subsystem: Any flyable ship needs this.
- Sensor base range: the normal sensor range, at 100% power, in game units. Objects within this range will be detected. Objects within half of this range will be identified.
- Max # of probes: the number of probes this ship can carry at once.
- Impulse Engine System: Any ship that wants to move under its own power needs this.
- Max speed: the maximum speed this ship can attain under its own power, in game units/second.
- Max acceleration: the maximum acceleration this ship can apply per second.
- Max angular velocity: the maximum speed at which the ship can turn.
- Max angular acceleration: the maximum acceleration this ship which this ship can apply for turning.
- Engine sound name: the name of the sound (not the file name) for the engine noise.
- Warp Engine System: any ship that wants to warp needs one.
- Engine Property: this is a single engine on the ship. (Warp or impulse)
- Power System: this produces and distributes power on the ship, to all of the powered subsystems.
- Power output/second: This is how much power is produced per second, if the system is not damaged.
- Main battery limit: This is how much power can be stored in the main battery.
- Backup battery limit: This is how much power can be stored in the backup battery.
- Main conduit capacity: This is how much power can be drawn from the main battery per second.
- Backup conduit capacity: This is how much power can be drawn from the backup battery per second.
- Repair System: if the ship has one, damage will be repaired over time.
- Maximum repair points: this is how many points of damage can be repaired per second.
- Repair teams: this is how many systems can be repaired at once. The repair points available will be divided among the repair teams.
- Shield system: this protects a ship from damage.
- Glow color: this is the color that the shields glow when they are hit by weapons fire. Clicking Pick Color will bring up a standard color selector for you to make your choice.
- Glow decay time: unused.
- Shield strength: Here you specify the amount of damage points each shield can take when fully charged.
- Charge rate: this is the amount of points that will be restored per second to this shield, if the system is powered at 100%.
- Weapon systems: You must have a weapon system for each type of weapon on the ship. i.e. a torpedo system if you have torps on the ship, a phaser system if you have phasers, etc. You can only have one system of each type, although you can have as many weapons as you like.
- Type: Select the type of weapon system that this is.
- Single fire only: if this is checked, the weapon system can only fire one of its weapons at once.
- Slow weapon (AI needs to aim): modifies AI behavior so it knows that it needs to aim this weapon for best effect.
- Firing chain string: used to implement torpedo spread modes. It's a semicolon-delimited string, with weapon group numbers followed by a string used to display the name of the spread. (Zero is used for the group of all weapons, single-firing.)
- Weapons: These are things common to all weapons.
- Weapon ID: can be used to 'tag' weapons for mission-specific purposes. (you can determine which weapon fired by its ID)
- Dumb-fire capable: whether the weapon can fire without a target (torps, disruptors).
- Groups: which weapon groups this weapon belongs to. Used for building firing chains in Weapon Systems, as noted above.
- Damage radius factor: the radius of damage caused by this weapon. Anything within this range of a weapon strike will be damaged by this weapon. This also affects the radius of visible damage.
- Icon number: specifies the icon (from the WeaponIcons icon group) to use for this weapon on the player's weapons display.
- Icon above ship: specifies that the weapon icon should be in the layer above the ship icon, rather than below the ship icon.
- Icon position: specifies the x,y position for the weapon status icon in the player's weapons display.
- Energy Weapons: These are things common to all energy weapons (phasers, disruptors, tractors).
- Max charge: The maximum amount of charge that can be stored in this weapon. Not applicable for tractor beams.
- Max damage: The maximum amount of damage that can be dealt by this weapon, in ideal conditions. For tractor beams, this is the amount of force applied.
- Max damage distance: The maximum distance at which full damage will be done by this weapon. (or in which the tractor beam will fire)
- Min. firing charge: The minimum amount of charge needed to fire this weapon. Used to prevent cases where weapons fire for a fraction of a second, drain, recharge, fire, etc. Not applicable for tractor beams.
- Normal discharge rate: The amount of charge drained per second, while the weapon is firing. Not applicable for tractor beams.
- Recharge rate: The amount of charge this weapon regains per second, if the weapon system is powered at 100%. Not applicable for tractor beams.
- Fire sound: the name of the sound (not the file name) used when the weapon fires.
- Firing arc icon number: icon number for icon used to indicate when the target is in this weapon's firing arc.
- Icon offset: offset from the weapon's icon for the firing arc icon.
- Phasers: These are your primary beam weapons.
- Orientation: see Position/Orientation Property above. This affects the direction the phaser faces. As you change the orientation, you'll notice that the firing cone in the model viewer changes.
- Ellipse size: Phasers arcs are specified in terms of angles along an ellipse (to make phasers for Federation ships easier to implement). This specifies the length and width of the ellipse.
- Texture numbers: no longer used.
- Angles: These specify the angles along the ellipse that the phaser covers. Vertical angles are perpendicular to the plane of the ellipse. Changing these angles will change the firing cone in the model viewer, so you can keep an eye on how the firing arc looks.
- Colors: Here you can specify the colors for the phaser effect.
- Sides, Main radius, Taper radius, Core scale, Taper ratio, Taper min length, Taper max length, length texture tile/unit, perimeter tile, texture speed, texture name: These all specify how the phaser should look. Most of them are somewhat self-explanatory, so it is recommended that you just experiment with these values.
- Torpedoes:
- Direction, Right: see Position/Orientation Property above. Note that the right vector will be used to change the firing direction slightly if torpedoes are fired in non-single-fire mode.
- Immediate delay: the amount of time you must wait between firing torpedoes.
- Reload delay: how long it takes to reload a torpedo in this tube.
- Maximum ready: how many torpedoes can be loaded in this tube at once.
- Pulse weapons: these are disruptor-type weapons.
- Direction, Up, Right: see Position/Orientation Property above.
- Angles: similar to phaser firing arcs, except that these originate from a point rather than an ellipse. Like with phasers, you'll see a representation of the firing arc in the viewer window.
- Cooldown time: how long you must wait between shots.
- Script: the script used for whatever shoots out of this gun. i.e. Tactical.Projectiles.FusionBolt.
Advanced topics
This section discusses some advanced or special-purpose things in the editor.
Parent scripts
If you're trying to create a "souped up" version of a ship, it's often easier to just modify one or two things about it, than to create a new ship. You can do this with the parent script option, located under the Property menu. You will be prompted for a script from which to inherit (i.e. "ships.Hardpoints.galaxy"). When you save the script, it will be changed so that in the game, it loads "ships.Hardpoints.galaxy" first, and then loads the inheriting script.
Properties in the inheriting script with the same name as ones in the parent script will override them. For example, if you want to create a Galaxy with a better phaser system, you would create a script "SuperGalaxy", that inherits from "ships.Hardpoints.galaxy", but contains a property named "Phaser System", which is the modified phaser system. When the script is read by the game, the "Phaser System" in SuperGalaxy will override the one from the original script.
Localization concerns
The game will look for localized versions of subsystem names when building the target menu. It looks for them in the file "data/TGL/Subsystems.tgl", so if you want localized strings for your subsystem names, place localized strings in that file.
Created on ... January 31, 2002